Step 5: In-Depth CMake Library Concepts ======================================= While executables are mostly one-size-fits-all, libraries come in many different forms. There are static archives, shared objects, modules, object libraries, header-only libraries, and libraries which describe advanced CMake properties to be inherited by other targets, just to name a few. In this step you will learn about some of the most common kinds of libraries that CMake can describe. This will cover most of the in-project uses of :command:`add_library`. Libraries which are imported from dependencies (or exported by the project to be consumed as a dependency) will be covered in later steps. Background ^^^^^^^^^^ As we learned in ``Step1``, the :command:`add_library` command accepts the name of the library target to be created as its first argument. The second argument is an optional ```` for which the following values are valid: ``STATIC`` A :ref:`Static Library `: an archive of object files for use when linking other targets. ``SHARED`` A :ref:`Shared Library `: a dynamic library that may be linked by other targets and loaded at runtime. ``MODULE`` A :ref:`Module Library `: a plugin that may not be linked by other targets, but may be dynamically loaded at runtime using dlopen-like functionality. ``OBJECT`` An :ref:`Object Library `: a collection of object files which have not been archived or linked into a library. ``INTERFACE`` An :ref:`Interface Library `: a library target which specifies usage requirements for dependents but does not compile sources and does not produce a library artifact on disk. In addition, there are ``IMPORTED`` libraries which describe library targets from foreign projects or modules, imported into the current project. We will cover these briefly in later steps. ``MODULE`` libraries are most commonly found in plugin systems, or as extensions to runtime-loading languages like Python or Javascript. They act very similar to normal shared libraries, except they cannot be directly linked by other targets. They are sufficiently similar that we won't cover them in further depth here. Exercise 1 - Static and Shared ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While the :command:`add_library` command supports explicitly setting ``STATIC`` or ``SHARED``, and this is sometimes necessary, it is best to leave the second argument empty for most "normal" libraries which can operate as either. When not given a type, :command:`add_library` will create either a ``STATIC`` or ``SHARED`` library depending on the value of :variable:`BUILD_SHARED_LIBS`. If :variable:`BUILD_SHARED_LIBS` is true, a ``SHARED`` library will be created, otherwise it will be ``STATIC``. .. code-block:: cmake add_library(MyLib-static STATIC) add_library(MyLib-shared SHARED) # Depends on BUILD_SHARED_LIBRARY add_library(MyLib) This is desirable behavior, as it allows packagers to determine what kind of library will be produced, and ensure dependents link to that version of the library without needing to modify their source code. In some contexts, fully static builds are appropriate, and in others shared libraries are desirable. .. note:: CMake does not define the :variable:`BUILD_SHARED_LIBS` variable by default, meaning without project or user intervention :command:`add_library` will produce ``STATIC`` libraries. By leaving the second argument to :command:`add_library()` blank, projects provide additional flexibility to their packagers and downstream dependents. Goal ---- Build ``MathFunctions`` as a shared library. .. note:: On Windows, you might see warnings about an empty DLL, as ``MathFunctions`` doesn't export any symbols. Helpful Resources ----------------- * :variable:`BUILD_SHARED_LIBS` Files to Edit ------------- There are no files to edit. Getting Started --------------- The ``Help/guide/tutorial/Step5`` directory contains the complete, recommended solution to ``Step4``. This step is about building the ``MathFunctions`` library, there are no ``TODOs`` necessary. You can proceed directly to the build step. Build and Run ------------- We can configure using our preset, turning on :variable:`BUILD_SHARED_LIBS` with a :option:`-D ` flag. .. code-block:: console cmake --preset tutorial -DBUILD_SHARED_LIBS=ON Then we can build only the ``MathFunctions`` library with :option:`-t `. .. code-block:: console cmake --build build -t MathFunctions Verify a shared library is produced for ``MathFunctions`` then reset :variable:`BUILD_SHARED_LIBS`, either by reconfiguring with ``-DBUILD_SHARED_LIBS=OFF`` or deleting the ``CMakeCache.txt``. Solution -------- There are no changes to the project for this exercise. Exercise 2 - Interface Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Interface libraries are those which only communicate usage requirements for other targets, they do not build or produce any artifacts of their own. As such all the properties of an interface library must themselves be interface properties, specified with the ``INTERFACE`` :ref:`scope keywords `. .. code-block:: cmake add_library(MyInterface INTERFACE) target_compile_definitions(MyInterface INTERFACE MYINTERFACE_COMPILE_DEF) The most common kind of interface library in C++ development is a header-only library. Such libraries do not build anything, only providing the flags necessary to discover their headers. Goal ---- Add a header-only library to the tutorial project, and use it inside the ``Tutorial`` executable. Helpful Resources ----------------- * :command:`add_library` * :command:`target_sources` Files to Edit ------------- * ``MathFunctions/MathLogger/CMakeLists.txt`` * ``MathFunctions/CMakeLists.txt`` * ``MathFunctions/MathFunctions.cxx`` Getting Started --------------- In our previous discussions of :command:`target_sources(FILE_SET)`, we noted we can omit the ``TYPE`` parameter if the file set's name is the same as the file set's type. We also said we can omit the ``BASE_DIRS`` parameter if we want to use the current source directory as the only base directory. We're ready to introduce a third shortcut, we only need to include the ``FILES`` parameter if the headers are intended to be installed, such as public headers of a library. The ``MathLogger`` headers in this exercise are only used internally by the ``MathFunctions`` implementation. They will not be installed. This should make for a very abbreviated call to :command:`target_sources(FILE_SET)`. .. note:: The headers will be discovered by the compiler's dependency scanner to ensure correct incremental builds. It can be useful to list header files in these contexts anyway, as the list can be used to generate metadata some IDEs rely on. You can begin editing the ``Step5`` directory. Complete ``TODO 1`` through ``TODO 7``. Build and Run ------------- The preset has already been updated to use ``mathfunctions::sqrt`` instead of ``std::sqrt``. We can build and configure as usual. .. code-block:: console cmake --preset tutorial cmake --build build Verify that the ``Tutorial`` output now uses the logging framework. Solution -------- First we add a new ``INTERFACE`` library named ``MathLogger``. .. raw:: html
TODO 1: Click to show/hide answer .. literalinclude:: Step6/MathFunctions/MathLogger/CMakeLists.txt :caption: TODO 1: MathFunctions/MathLogger/CMakeLists.txt :name: MathFunctions/MathLogger/CMakeLists.txt-add_library :language: cmake :start-at: add_library :end-at: add_library .. raw:: html
Then we add the appropriate :command:`target_sources` call to capture the header information. We give this file set the name ``HEADERS`` so we can omit the ``TYPE``, we don't need ``BASE_DIRS`` as we will use the default of the current source directory, and we can exclude the ``FILES`` list because we don't intend to install the library. .. raw:: html
TODO 2: Click to show/hide answer .. literalinclude:: Step6/MathFunctions/MathLogger/CMakeLists.txt :caption: TODO 2: MathFunctions/MathLogger/CMakeLists.txt :name: MathFunctions/MathLogger/CMakeLists.txt-target_sources :language: cmake :start-at: target_sources( :end-at: ) .. raw:: html
Now we can add the ``MathLogger`` library to the ``MathFunctions`` linked libraries, and at the ``MathLogger`` folder to the project. .. raw:: html
TODO 3-4: Click to show/hide answer .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :caption: TODO 3: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-link-mathlogger :language: cmake :start-at: target_link_libraries( :end-at: MathLogger :append: ) .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :caption: TODO 4: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add-mathlogger :language: cmake :start-at: add_subdirectory(MathLogger :end-at: add_subdirectory(MathLogger .. raw:: html
Finally we can update ``MathFunctions.cxx`` to take advantage of the new logger. .. raw:: html
TODO 5-7: Click to show/hide answer .. literalinclude:: Step6/MathFunctions/MathFunctions.cxx :caption: TODO 5: MathFunctions/MathFunctions.cxx :name: MathFunctions/MathFunctions.cxx-mathlogger-header :language: c++ :start-at: cmath :end-at: MathLogger .. literalinclude:: Step6/MathFunctions/MathFunctions.cxx :caption: TODO 6: MathFunctions/MathFunctions.cxx :name: MathFunctions/MathFunctions.cxx-mathlogger-logger :language: c++ :start-at: mathlogger::Logger Logger :end-at: mathlogger::Logger Logger .. literalinclude:: Step6/MathFunctions/MathFunctions.cxx :caption: TODO 7: MathFunctions/MathFunctions.cxx :name: MathFunctions/MathFunctions.cxx-mathlogger-code :language: c++ :start-at: Logger.Log(std::format("Computing sqrt of {} to be {}\n" :end-at: std::format :dedent: 4 .. raw:: html
Exercise 3 - Object Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Object libraries have several advanced uses, but also tricky nuances which are difficult to fully enumerate in the scope of this tutorial. .. code-block:: cmake add_library(MyObjects OBJECT) The most obvious drawback to object libraries is the objects themselves cannot be transitively linked. If an object library appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` of a target, the dependents which link that target will not "see" the objects. The object library will act like an ``INTERFACE`` library in such contexts. In the general case, object libraries are only suitable for ``PRIVATE`` or ``PUBLIC`` consumption via :command:`target_link_libraries`. A common use case for object libraries is coalescing several library targets into a single archive or shared library object. Even within a single project libraries may be maintained as different targets for a variety of reasons, such as belonging to different teams within an organization. However, it may be desirable to distribute these as a single consumer-facing binary. Object libraries make this possible. Goal ---- Add several object libraries to the ``MathFunctions`` library. Helpful Resources ----------------- * :command:`target_link_libraries` * :command:`add_subdirectory` Files to Edit ------------- * ``MathFunctions/CMakeLists.txt`` * ``MathFunctions/MathFunctions.h`` * ``Tutorial/Tutorial.cxx`` Getting Started --------------- Several extensions for our ``MathFunctions`` library have been made available (we can imagine these coming from other teams in our organization). Take a minute to look at the targets made available in ``MathFunctions/MathExtensions``. Then complete ``TODO 8`` through ``TODO 11``. Build and Run ------------- There's no reconfiguration needed, we can build as usual. .. code-block:: console cmake --build build Verify the output of ``Tutorial`` now includes the verification message. Also take a minute to inspect the build directory under ``build/MathFunctions/MathExtensions``. You should find that, unlike ``MathFunctions``, no archives are produced for any of the object libraries. Solution -------- First we will add links for all the object libraries to ``MathFunctions``. These are ``PUBLIC``, because we want the objects to be added to the ``MathFunctions`` library as part of its own build step, and we want the headers to be available to consumers of the library. Then we add the ``MathExtensions`` subdirectoy to the project. .. raw:: html
TODO 8-9: Click to show/hide answer .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :caption: TODO 8: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-link-objects :language: cmake :start-at: target_link_libraries( :end-at: ) .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :caption: TODO 9: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add-objs :language: cmake :start-at: add_subdirectory(MathExtensions :end-at: add_subdirectory(MathExtensions .. raw:: html
To make the extensions available to consumers, we include their headers in the ``MathFunctions.h`` header. .. raw:: html
TODO 10: Click to show/hide answer .. literalinclude:: Step6/MathFunctions/MathFunctions.h :caption: TODO 10: MathFunctions/MathFunctions.h :name: MathFunctions/MathFunctions.h-include-objects :language: c++ :start-at: OpAdd :end-at: OpSub .. raw:: html
Finally we can take advantage of the extensions in the ``Tutorial`` program. .. raw:: html
TODO 11: Click to show/hide answer .. literalinclude:: Step6/Tutorial/Tutorial.cxx :caption: TODO 11: Tutorial/Tutorial.cxx :name: Tutorial/Tutorial.cxx-use-objects :language: c++ :start-at: OpMul :end-at: checkValue); :dedent: 2 .. raw:: html